Miscellaneous implementation notes for all components of ResEd
==============================================================

Contents
--------

1  Debugging
2  !Run files
3  Calling SWIs


1  Debugging
------------

Set #define DEBUG 1 in h.debug to activate any debugging statements in the
code; these may be bracketed by:

#if DEBUG
  ....
#endif

or the following output function call can be made:

  dprintf (format, ... );

Output from dprintf is sent to a file called 'logfile' inside the application
directory.


Set #define DBMALLOC 1 inside h.dbmalloc to substitute special checking
allocation and freeing routines for malloc, calloc, realloc and free. These
routines add "guard" structures around each allocated fragment of memory,
and also do a complete heap consistency check whenever store is allocated
or freed.

Any errors are output using dprintf - and a single plus sign '+' is written
before starting each check.

Just before program exit, a list of all blocks that remain allocated is also
sent to the log file. This list typically contains blocks allocated as
follows:

  For the shell:

    2 blocks for the Messages file.
    1 block for the Registry.
    1 block for each template (11).
    1 block for each menu (4).
    1 block for each menu entry that is more than 12 characters long (8).
    1 block for each CSE (3).
    1 block for each object class (14).
    2 blocks for each template in the Palette (15*2).
    1 block for the Palette document.
    1 block for the Palette document's "mapping".

    A total of 75 heap blocks active.

  For the Menu CSE:

    2 blocks for the Messages file.
    1 block for the Registry.
    1 block for each template (4).
    1 block for each menu (2).
    1 block for each menu entry that is more than 12 characters long (6).
    2 blocks for each menu entry in the Palette (2*3).
    2 blocks for each separator in the Palette (2*2).
    2 blocks for the Palette document.

    A total of 25 heap blocks active.

  For the Window CSE:

    2 blocks for the Messages file.
    1 block for the Registry.
    1 block for each template (26).
    1 block for each menu (7).
    1 block for each menu entry that is more than 12 characters long (29).
    1 block for "transpval" (in c.colours).
    1 block for each gadget in the Palette (15).
    1 block for each gadget string that has to be "cloned" (13).
    1 block for each gadget "extension" required (8).
    3 blocks for the Palette window.

    A total of 105 heap blocks active.

  For the Misc CSE:

    2 blocks for the Messages file.
    1 block for the Registry.
    1 block for each template (13).
    1 block for each menu (5).
    1 block for each menu entry that is more than 12 characters long (10).
    2 blocks for the Font menus (if a Font Menu has been displayed).
    1 block for "noneval" (in c.colours).

    A total of 34 heap blocks active.


2  !Run files
-------------

Make sure that these are *not* terminated by a newline! If, for example, a
CSE !Run file is terminated with a newline, then quitting does not complete
unless the user also presses ESC.


When an error causes a traceback, the output can be sent to a file by adding,
eg, "2> <ResEd$Misc$Dir>.pm" to the Run command at the end of the file.


3  Calling SWIs
---------------

SWIs are called using Steve's SWI wrapper as, eg:

        err = swi(Wimp_ForceRedraw,
                     R0, -1,
                     R1, outl.visarea.minx,
                     R2, vis.visarea.maxy,
                     R3, outl.visarea.maxx,
                     R4, outl.visarea.maxy,  END);

See common.h.swicall for details of the format; this header file also
contains a list of #defines for SWI numbers known at the time, thus making
the source independent of gratuitous changes to the SWI list.

The source of the swi routine itself can be found in common.s.swicall.
